ci(openapi): Improve OpenAPI checks #2190

vdusek · 2026-01-20T18:20:05Z

Issue

Relates: Ensure OpenAPI specs can serve as a reliable source of truth for typed client generation #2182

Description

Add Redocly and Spectral for OpenAPI lint checks.
- Maybe using only Redocly is enough? Let me know your opinion.
- Fixed 62 Spectral validation errors (missing required fields, incorrect types, nullable issues).
- In Redocly, we have the errors set as warnings, I will resolve them in chore(openapi): Update to Open API v3.1.2 #2188.
Add YAML style lint check.
- Only for the OpenAPI definitions.
- Unify and enforce style.
- Double quotes as in JSON or single quotes as we prefer in Py and AFAIK in JS as well, any opinion? 🙂
Remove Go API client generation job, as discussed in chore(openapi): Update to Open API v3.1.2 #2188.
- It is replaced with the validate step, where we validate the bundled specification with the Redocly and check its size.
The new OpenAPI CI is: lint-check -> build -> validate.

Testing

CI passes

Note

Strengthens OpenAPI quality checks and streamlines CI.

Adds OpenAPI checks workflow (.github/workflows/openapi-ci.yaml) with Redocly/Spectral/YAML linting, bundle build/upload, and post-build validation (including bundle size check)
Removes legacy workflow (.github/workflows/openapi.yaml) and Go client codegen config (codegen/oapi-codegen-go/*), and cleans .gitignore
Introduces Spectral config (.spectral.yaml) with rule overrides and adds YAML linting via ESLint (eslint.config.mjs) scoped to apify-api/**, with an exception for openapi/openapi.yaml
Normalizes and fixes many OpenAPI YAML files (schemas, paths, components): consistent quoting/arrays, corrected $ref paths, examples, required lists, and descriptions

^{Written by Cursor Bugbot for commit b09198c. Configure here.}

apify-service-account · 2026-01-20T18:23:55Z

Preview for this PR was built for commit b09198cc and is ready at https://pr-2190.preview.docs.apify.com!

apify-service-account · 2026-01-20T18:31:00Z

Preview for this PR was built for commit 697ec440 and is ready at https://pr-2190.preview.docs.apify.com!

apify-service-account · 2026-01-20T18:39:06Z

Preview for this PR was built for commit 26e8706a and is ready at https://pr-2190.preview.docs.apify.com!

apify-service-account · 2026-01-20T18:46:49Z

Preview for this PR was built for commit 63228a82 and is ready at https://pr-2190.preview.docs.apify.com!

apify-service-account · 2026-01-20T18:54:33Z

Preview for this PR was built for commit 80e67ec3 and is ready at https://pr-2190.preview.docs.apify.com!

janbuchar · 2026-01-21T08:26:40Z

Maybe using only Redocly is enough? Let me know your opinion.

I don't know, if Spectral doesn't take too much time, we can keep both 🤷

Fixed 62 Spectral validation errors (missing required fields, incorrect types, nullable issues).

Looks like it's doing useful work then - unless it's the same as what Redocly reports

Double quotes as in JSON or single quotes as we prefer in Py and AFAIK in JS as well, any opinion? 🙂

They are optional in most cases anyway, so no strong feelings. Which quotes produce the smaller diff in this PR?

Remove Go API client generation job, as discussed in chore(openapi): Update to Open API v3.1 #2188.

It is replaced with the validate step, where we validate the bundled specification with the Redocly and check its size.

cc @bliuchak as he added the original validation step.

fnesveda · 2026-01-21T08:34:11Z

Double quotes as in JSON or single quotes as we prefer in Py and AFAIK in JS as well, any opinion? 🙂

They are optional in most cases anyway, so no strong feelings. Which quotes produce the smaller diff in this PR?

I have a slight preference towards double quotes, but I don't really care. I would see if there are more strings that need escaping single quotes or double quotes, and choose based on that.

But whichever we choose, can we enforce them everywhere?

I'd rather have it consistent than have to think "why are there quotes here but not here?"
Also, if a string doesn't have quotes, and then you change it so that it requires them (either by adding a word like "shouldn't" or some phrase in quotes), it will make for a slightly messier diff.

janbuchar

No way I'm gonna review all the changes, so I'm going to trust you 😁

janbuchar · 2026-01-21T08:29:22Z

package.json

        "redoc:build:clean": "npm run redoc:build:clean:yaml && npm run redoc:build:clean:json",
        "redoc:build:clean:yaml": "redocly bundle apify-api/openapi/openapi.yaml --skip-decorator=apify/legacy-doc-url-decorator --skip-decorator=apify/client-references-links-decorator --skip-decorator=apify/code-samples-decorator -o static/api/openapi.yaml",
        "redoc:build:clean:json": "redocly bundle apify-api/openapi/openapi.yaml --skip-decorator=apify/legacy-doc-url-decorator --skip-decorator=apify/client-references-links-decorator --skip-decorator=apify/code-samples-decorator -o static/api/openapi.json",
+        "openapi:build": "npm run redoc:build:clean",


It feels like there are way too many package scripts now. Can we perhaps remove some of the older, redoc-prefixed ones? 😁

Well, I didn't want to break commands people are already used to, but OK 😬.

All OpenAPI-related npm scripts are now grouped under the "openapi" prefix. Why? Because the workflow is no longer using only Redoc (it also uses Astral and ESLint for some commands).

Script mapping

redoc:start -> openapi:preview

redoc:build -> openapi:bundle

redoc:build:clean -> openapi:build

redoc:build:clean:yaml -> openapi:build:yaml

redoc:build:clean:json -> openapi:build:json

Removed scripts

redoc:test - This was just redocly lint && redoc:build and was only used in CI, where it has been updated.

redoc:test2 - This referenced a non-existent bin/schemathesis script and was not used anywhere.

vdusek · 2026-01-21T08:53:03Z

I have a slight preference towards double quotes, but I don't really care. I would see if there are more strings that need escaping single quotes or double quotes, and choose based on that.

If double quotes are configured but the string itself contains double quotes, for example 'He said, "Crawlee is the best"', the linter won't complain. It prefers switching to the other quote style rather than escaping. The same applies vice versa.

And it enforces the use of quotes only where they are actually necessary.

But whichever we choose, can we enforce them everywhere?

You mean everywhere in this repository?

Also, if a string doesn't have quotes, and then you change it so that it requires them (either by adding a word like "shouldn't" or some phrase in quotes) it will make for a slightly messier diff.

AFAIK this is not an example where YAML would require quotes - quoting is only necessary in cases where the value would otherwise be interpreted as a different type, for example "42", "3.14", "{hello: world}", ...

So taking this together with the fact that it enforces the use of quotes only where they are necessary, this should be OK.

fnesveda · 2026-01-21T08:56:17Z

Ah, thanks for the explanation, I thought it works differently 🤦 In that case I also don't care very much, whichever you prefer.

- All OpenAPI-related npm scripts are now grouped under the "openapi" prefix, as the workflow is no longer using Redoc only (it also uses Spectral and ESLint for some commands). Script mapping - redoc:start -> openapi:preview - redoc:build -> openapi:bundle - redoc:build:clean -> openapi:build - redoc:build:clean:yaml -> openapi:build:yaml - redoc:build:clean:json -> openapi:build:json Removed scripts - redoc:test - This was just `redocly lint && redoc:build` and was only used in CI, where it has been updated. - redoc:test2 - This referenced a non-existent `bin/schemathesis` script and was not used anywhere.

fnesveda

I haven't checked the whole thing, just the important parts, and looks good 👍

apify-service-account · 2026-01-21T09:25:04Z

Preview for this PR was built for commit d302e0c8 and is ready at https://pr-2190.preview.docs.apify.com!

vdusek · 2026-01-21T09:38:49Z

I'm merging this to unblock #2188 and related work there.

@bliuchak If you would find the new validation step not robust enough, we can try to come up with a better solution in a follow-up PR.

vdusek added 4 commits January 20, 2026 18:48

ci(openapi): Improve OpenAPI checks

9612bf2

Rm codegen go

defa290

Better validate step

994ffb5

quoting

b09198c

vdusek added this to the 132nd sprint - Tooling team milestone Jan 20, 2026

vdusek self-assigned this Jan 20, 2026

vdusek added the t-tooling Issues with this label are in the ownership of the tooling team. label Jan 20, 2026

vdusek requested review from fnesveda and janbuchar as code owners January 20, 2026 18:20

vdusek added 2 commits January 20, 2026 19:27

improve naming

17b17fd

fix redocly lint command

697ec44

vdusek added the adhoc Ad-hoc unplanned task added during the sprint. label Jan 20, 2026

Fix CI error

26e8706

vdusek added 2 commits January 20, 2026 19:41

fix

63228a8

double quoting (?)

80e67ec

janbuchar approved these changes Jan 21, 2026

View reviewed changes

fnesveda approved these changes Jan 21, 2026

View reviewed changes

vdusek merged commit f1d9dee into master Jan 21, 2026
12 checks passed

vdusek deleted the add-api-spec-lint branch January 21, 2026 09:36

ci(openapi): Improve OpenAPI checks #2190

ci(openapi): Improve OpenAPI checks #2190

Uh oh!

Conversation

vdusek commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue

Description

Testing

Uh oh!

apify-service-account commented Jan 20, 2026

Uh oh!

apify-service-account commented Jan 20, 2026

Uh oh!

apify-service-account commented Jan 20, 2026

Uh oh!

apify-service-account commented Jan 20, 2026

Uh oh!

apify-service-account commented Jan 20, 2026

Uh oh!

janbuchar commented Jan 21, 2026

Uh oh!

fnesveda commented Jan 21, 2026

Uh oh!

janbuchar left a comment

Choose a reason for hiding this comment

Uh oh!

janbuchar Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

vdusek Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

vdusek commented Jan 21, 2026

Uh oh!

fnesveda commented Jan 21, 2026

Uh oh!

fnesveda left a comment

Choose a reason for hiding this comment

Uh oh!

apify-service-account commented Jan 21, 2026

Uh oh!

Uh oh!

vdusek commented Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

vdusek commented Jan 20, 2026 •

edited

Loading